---
title: 환경 변수 사용
sidebar:
  label: 환경 변수
description: Astro 프로젝트에서 환경 변수를 사용하는 방법을 알아보세요.
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

Astro는 [Vite의 내장 환경 변수 지원](#vite의-내장-지원)에 대한 접근 권한을 제공하며, 현재 프로젝트의 구성 값 (`site`, `base` 등), 프로젝트가 개발 또는 프로덕션 환경에서 실행 중인지 여부 등에 접근할 수 있도록 [몇 가지 기본 환경 변수](#기본-환경-변수)를 포함합니다.

Astro는 [타입 안정성을 갖춘 환경 변수를 사용하고 구성하는 방법](#타입-안전-환경-변수)도 제공합니다. Astro 컨텍스트 (예: Astro 컴포넌트, 라우트 및 엔드포인트, UI 프레임워크 컴포넌트, 미들웨어)에서 사용할 수 있으며, [Astro 구성의 스키마](/ko/reference/configuration-reference/#env)를 통해 관리됩니다.

## Vite의 내장 지원

Astro는 빌드 시 정적으로 대체되는 환경 변수에 대한 Vite의 내장 지원을 사용하며, 환경 변수를 다루기 위한 [모든 메서드](https://ko.vite.dev/guide/env-and-mode.html)를 사용할 수 있습니다.

서버 측 코드에서는 _모든_ 환경 변수를 사용할 수 있지만, 보안상의 이유로 클라이언트 측 코드에서는 `PUBLIC_` 접두사가 붙은 환경 변수만 사용할 수 있습니다.

```ini title=".env"
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there
```

이 예시에서 `PUBLIC_ANYBODY` (`import.meta.env.PUBLIC_ANYBODY`를 통해 접근 가능)는 서버 또는 클라이언트 코드에서 사용할 수 있지만, `SECRET_PASSWORD` (`import.meta.env.SECRET_PASSWORD`를 통해 접근 가능)는 서버 측에서만 사용할 수 있습니다.

:::caution
`.env` 파일은 [구성 파일](#astro-구성-파일)에서 로드되지 않습니다.
:::

### TypeScript를 위한 IntelliSense

기본적으로 Astro는 `astro/client.d.ts`에서 `import.meta.env`에 대한 타입 정의를 제공합니다.

`.env.[mode]` 파일에서 더 많은 사용자 정의 환경 변수를 정의할 수 있지만, `PUBLIC_` 접두사가 붙은 사용자 정의 환경 변수에 대해 TypeScript IntelliSense를 얻고 싶을 수 있습니다.

이를 위해 `src/`에 `env.d.ts` 파일을 생성하여 [전역 타입을 확장](/ko/guides/typescript/#전역-타입-확장하기)하고 `ImportMetaEnv`를 다음과 같이 구성할 수 있습니다.

```ts title="src/env.d.ts"
interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // 더 많은 환경 변수...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

## 기본 환경 변수

Astro는 몇 가지 기본 환경 변수를 포함합니다.

- `import.meta.env.MODE`: 사이트가 실행 중인 모드입니다. `astro dev`를 실행하면 `development`이고, `astro build`를 실행하면 `production`입니다.
- `import.meta.env.PROD`: 사이트가 프로덕션 환경에서 실행 중이면 `true`, 그렇지 않으면 `false`입니다.
- `import.meta.env.DEV`: 사이트가 개발 환경에서 실행 중이면 `true`, 그렇지 않으면 `false`입니다. 항상 `import.meta.env.PROD`의 반대입니다.
- `import.meta.env.BASE_URL`: 사이트가 제공되는 기본 URL입니다. [`base` 구성 옵션](/ko/reference/configuration-reference/#base)에 의해 결정됩니다.
- `import.meta.env.SITE`: 프로젝트의 `astro.config`에 지정된 [`site` 옵션](/ko/reference/configuration-reference/#site)으로 설정됩니다.
- `import.meta.env.ASSETS_PREFIX`: [`build.assetsPrefix` 구성 옵션](/ko/reference/configuration-reference/#buildassetsprefix)이 설정된 경우 Astro에서 생성된 자산 링크의 접두사입니다. Astro에서 처리하지 않는 자산 링크를 생성하는 데 사용할 수 있습니다.

다른 환경 변수처럼 사용하세요.

```ts utils.ts
const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;
```

## 환경 변수 설정

### `.env` 파일

환경 변수는 프로젝트 디렉터리의 `.env` 파일에서 로드할 수 있습니다.

프로젝트 디렉터리에 `.env` 파일을 생성하고 몇 가지 변수를 추가하기만 하면 됩니다.

```ini title=".env"
# 서버에서 실행될 때만 사용할 수 있습니다!
DB_PASSWORD="foobar"

# 어디서나 사용할 수 있습니다!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
```

`.production`, `.development` 또는 사용자 정의 모드 이름을 파일 이름에 추가할 수도 있습니다 (예: `.env.testing`, `.env.staging`). 이를 통해 서로 다른 시간에 다른 환경 변수 집합을 사용할 수 있습니다.

`astro dev` 및 `astro build` 명령은 각각 `"development"` 및 `"production"` 모드를 기본값으로 사용합니다. [`--mode` 플래그](/ko/reference/cli-reference/#--mode-string)와 함께 이러한 명령을 실행하여 `mode`에 대한 다른 값을 전달하고, 일치하는 `.env` 파일을 로드할 수 있습니다.

이를 통해 다양한 API에 연결하여 개발 서버를 실행하거나 사이트를 빌드할 수 있습니다.

<PackageManagerTabs>
 <Fragment slot="npm">
    ```shell
    # "스테이징" API에 연결된 개발 서버를 실행합니다.
    npm run astro dev -- --mode staging

    # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
    npm run astro build -- --devOutput

    # "테스트" API에 연결되는 사이트를 빌드합니다.
    npm run astro build -- --mode testing
    ```
 </Fragment>
 <Fragment slot="pnpm">
    ```shell
    # "스테이징" API에 연결된 개발 서버를 실행합니다.
    pnpm astro dev --mode staging

    # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
    pnpm astro build --devOutput

    # "테스트" API에 연결되는 사이트를 빌드합니다.
    pnpm astro build --mode testing
    ```
 </Fragment>
  <Fragment slot="yarn">
    ```shell
    # "스테이징" API에 연결된 개발 서버를 실행합니다.
    yarn astro dev --mode staging

    # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
    yarn astro build --devOutput

    # "테스트" API에 연결되는 사이트를 빌드합니다.
    yarn astro build --mode testing
    ```
 </Fragment>
</PackageManagerTabs>

`.env` 파일에 대한 자세한 내용은 [Vite 문서](https://ko.vite.dev/guide/env-and-mode.html#env-files)를 참조하세요.

### Astro 구성 파일

Astro는 다른 파일을 로드하기 전에 구성 파일을 평가합니다. 즉, `astro.config.mjs`에서 `.env` 파일에 설정된 환경 변수에 접근하기 위해 `import.meta.env`를 사용할 수 없습니다.

[CLI에서 설정한 것](#cli-사용)과 같은 다른 환경 변수에 접근하기 위해 구성 파일에서 `process.env`를 사용할 수 있습니다.

[Vite의 `loadEnv` 도우미](https://ko.vite.dev/config/#using-environment-variables-in-config)를 사용하여 `.env` 파일을 수동으로 로드할 수도 있습니다.

```js title="astro.config.mjs"
import { loadEnv } from "vite";

const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
```

:::note
`pnpm`은 프로젝트에 직접 설치되지 않은 모듈을 가져오는 것을 허용하지 않습니다. `pnpm`을 사용하는 경우 `loadEnv` 도우미를 사용하려면 `vite`를 설치해야 합니다.

```sh
pnpm add -D vite
```
:::

### CLI 사용

프로젝트를 실행할 때 환경 변수를 추가할 수도 있습니다.

<PackageManagerTabs>
 <Fragment slot="yarn">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev
    ```
 </Fragment>
 <Fragment slot="npm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev
    ```
 </Fragment>
 <Fragment slot="pnpm">
    ```shell
    PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev
    ```
 </Fragment>
</PackageManagerTabs>

## 환경 변수 가져오기

Astro의 환경 변수는 `process.env` 대신 [ES2020에 추가된 `import.meta` 기능](https://tc39.es/ecma262/2020/#prod-ImportMeta)을 사용하여 `import.meta.env`로 접근합니다.

예를 들어 `PUBLIC_POKEAPI` 환경 변수를 가져오려면 `import.meta.env.PUBLIC_POKEAPI`를 사용하세요.

```js /(?<!//.*)import.meta.env.[A-Z_]+/
// import.meta.env.SSR === true인 경우 가져옵니다.
const data = await db(import.meta.env.DB_PASSWORD);

// import.meta.env.SSR === false인 경우 가져옵니다.
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);
```

SSR을 사용하는 경우, 사용 중인 SSR 어댑터에 따라 런타임에 환경 변수에 접근할 수 있습니다. 대부분의 어댑터에서는 `process.env`로 환경 변수에 접근할 수 있지만, 일부 어댑터는 다르게 작동합니다. Deno 어댑터의 경우 `Deno.env.get()`을 사용합니다. Cloudflare 어댑터를 사용할 때 환경 변수를 처리하기 위해 [Cloudflare 런타임에 접근하는 방법](/ko/guides/integrations-guide/cloudflare/#cloudflare-런타임)을 참조하세요. Astro는 먼저 서버 환경에서 변수를 확인하고, 존재하지 않으면 `.env` 파일에서 찾습니다.

## 타입 안전 환경 변수

`astro:env` API를 사용하면 [설정한 환경 변수](#환경-변수-설정)에 대한 타입 안전 스키마를 구성할 수 있습니다. 이를 통해 서버 또는 클라이언트에서 사용할 수 있는지 여부를 나타내고 데이터 타입 및 추가 속성을 정의할 수 있습니다.

<ReadMore>어댑터를 개발 중이신가요? [`astro:env`와 호환되는 어댑터를 만드는 방법](/ko/reference/adapter-reference/#envgetsecret)을 확인하세요.</ReadMore>

### 기본 사용법

#### 스키마 정의

스키마를 구성하려면 Astro 구성에 `env.schema` 옵션을 추가하세요.

```js title="astro.config.mjs" ins={4-8}
import { defineConfig } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})
```

그런 다음 `envField` 도우미를 사용하여 [변수를 문자열, 숫자, enum 또는 부울로 등록](#데이터-타입)할 수 있습니다. 각 변수에 대한 `context` (`"client"` 또는 `"server"`) 및 `access` (`"secret"` 또는 `"public"`)를 제공하여 [환경 변수의 종류](#변수-타입)를 정의하고 객체에 `optional` 또는 `default`와 같은 추가 속성을 전달합니다.

```js title="astro.config.mjs" ins="envField"
import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})
```

`astro dev` 또는 `astro build`를 실행하면 타입이 생성되지만, `astro sync`를 실행하여 타입만 생성할 수도 있습니다.

#### 스키마의 변수 사용

적절한 `/client` 또는 `/server` 모듈에서 정의된 변수를 가져와서 사용하세요.

```astro
---
import { API_URL } from "astro:env/client";
import { API_SECRET_TOKEN } from "astro:env/server";

const data = await fetch(`${API_URL}/users`, {
	method: "GET",
	headers: {
		"Content-Type": "application/json",
		"Authorization": `Bearer ${API_SECRET_TOKEN}`
	},
})
---

<script>
  import { API_URL } from "astro:env/client";
  
  fetch(`${API_URL}/ping`)
</script>
```

### 변수 타입

스키마에 정의된 `context` (`"client"` 또는 `"server"`)와 `access` (`"secret"` 또는 `"public"`) 설정의 조합에 따라 세 가지 종류의 환경 변수를 사용할 수 있습니다.

- **공개 클라이언트 변수**: 이러한 변수는 최종 클라이언트 및 서버 번들에 모두 포함되며, `astro:env/client` 모듈을 통해 클라이언트와 서버 모두에서 접근할 수 있습니다.

   ```js
   import { API_URL } from "astro:env/client";
   ```

- **공개 서버 변수**: 이러한 변수는 최종 서버 번들에 포함되며, `astro:env/server` 모듈을 통해 서버에서 접근할 수 있습니다.

   ```js
   import { PORT } from "astro:env/server";
   ```

- **비밀 서버 변수**: 이러한 변수는 최종 번들의 일부가 아니며, `astro:env/server` 모듈을 통해 서버에서 접근할 수 있습니다.

   ```js
   import { API_SECRET } from "astro:env/server";
   ```
   
   기본적으로, `astro:env/server` 모듈에서 무언가를 가져올 때마다 모든 비밀 변수가 검증됩니다. 이는 비밀 변수를 가져오지 않은 경우에도 검증될 수 있음을 의미합니다. 빌드 중에 이 검증을 통과하기 위해 [더미 환경 변수를 전달](#환경-변수-설정)해야 할 수도 있습니다.

   [`validateSecrets: true`를 구성](/ko/reference/configuration-reference/#envvalidatesecrets)하여 시작 시 비밀 변수 유효성 검사를 활성화할 수도 있습니다.

:::note
**비밀 클라이언트 변수**는 지원되지 않습니다. 이 데이터를 클라이언트로 안전하게 전송할 방법이 없기 때문입니다. 따라서 스키마에서 `context: "client"`와 `access: "secret"`을 모두 구성하는 것은 불가능합니다.
:::

### 데이터 타입

현재 문자열, 숫자, enum 및 부울의 네 가지 데이터 타입이 지원됩니다.

```js
import { envField } from "astro/config";

envField.string({
   // context & access
   optional: true,
   default: "foo",
})

envField.number({
   // context & access
   optional: true,
   default: 15,
})

envField.boolean({
   // context & access
   optional: true,
   default: true,
})

envField.enum({
   // context & access
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})
```

<ReadMore>유효성 검사 필드의 전체 목록은 [`envField` API 참조](/ko/reference/configuration-reference/#envschema)를 확인하세요.</ReadMore>

## 비밀 변수를 동적으로 검색

스키마를 정의했음에도 불구하고, 특정 비밀 변수의 원시 값을 검색하거나 스키마에 정의되지 않은 비밀 변수를 검색해야 할 수 있습니다. 이 경우 `astro:env/server`에서 내보낸 `getSecret()`을 사용할 수 있습니다.

```js
import {
   FOO, // boolean
   getSecret
} from "astro:env/server";

getSecret("FOO"); // string | undefined
```

<ReadMore>[API 참조](/ko/reference/modules/astro-env/#getsecret)에서 자세히 알아보세요.</ReadMore>

### 제한 사항

`astro:env`는 가상 모듈이므로 Astro 컨텍스트에서만 사용할 수 있습니다. 예를 들어 다음과 같은 곳에서 사용할 수 있습니다.

- 미들웨어
- Astro 라우트 및 엔드포인트
- Astro 컴포넌트
- 프레임워크 컴포넌트
- 모듈
   
다음과 같은 곳에서는 사용할 수 없으므로 `process.env`를 사용해야 합니다.

- `astro.config.mjs`
- 스크립트
